---
title: Run (span) data format
sidebarTitle: Run (span) data format
---

<Check>
Before diving into this content, it might be helpful to read the following:

* [Conceptual guide on tracing and runs](/langsmith/observability-concepts)
</Check>

LangSmith stores and processes trace data in a simple format that is easy to export and import.

Many of these fields are optional or not important to know about but are included for completeness. The **bolded** fields are the most important ones to know about.

| Field Name                    | Type             | Description                                                                                                                   |
| ----------------------------- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| **id**                        | UUID             | Unique identifier for the span.                                                                                               |
| **name**                      | string           | The name associated with the run.                                                                                             |
| **inputs**                    | object           | A map or set of inputs provided to the run.                                                                                   |
| **run\_type**                 | string           | Type of run, e.g., "llm", "chain", "tool".                                                                                    |
| **start\_time**               | datetime         | Start time of the run.                                                                                                        |
| **end\_time**                 | datetime         | End time of the run.                                                                                                          |
| **extra**                     | object           | Any extra information run.                                                                                                    |
| **error**                     | string           | Error message if the run encountered an error.                                                                                |
| **outputs**                   | object           | A map or set of outputs generated by the run.                                                                                 |
| **events**                    | array of objects | A list of event objects associated with the run. This is relevant for runs executed with streaming.                           |
| **tags**                      | array of strings | Tags or labels associated with the run.                                                                                       |
| **trace\_id**                 | UUID             | Unique identifier for the trace the run is a part of. This is also the `id` field of the root run of the trace                |
| **dotted\_order**             | string           | Ordering string, hierarchical. Format: `run_start_time`Z`run_uuid`.`child_run_start_time`Z`child_run_uuid`...                 |
| **status**                    | string           | Current status of the run execution, e.g., "error", "pending", "success"                                                      |
| **child\_run\_ids**           | array of UUIDs   | List of IDs for all child runs.                                                                                               |
| **direct\_child\_run\_ids**   | array of UUIDs   | List of IDs for direct children of this run.                                                                                  |
| **parent\_run\_ids**          | array of UUIDs   | List of IDs for all parent runs.                                                                                              |
| **feedback\_stats**           | object           | Aggregations of feedback statistics for this run                                                                              |
| **reference\_example\_id**    | UUID             | ID of a reference example associated with the run. This is usually only present for evaluation runs.                          |
| **total\_tokens**             | integer          | Total number of tokens processed by the run.                                                                                  |
| **prompt\_tokens**            | integer          | Number of tokens in the prompt of the run.                                                                                    |
| **completion\_tokens**        | integer          | Number of tokens in the completion of the run.                                                                                |
| **total\_cost**               | string           | Total cost associated with processing the run.                                                                                |
| **prompt\_cost**              | string           | Cost associated with the prompt part of the run.                                                                              |
| **completion\_cost**          | string           | Cost associated with the completion of the run.                                                                               |
| **first\_token\_time**        | datetime         | Time when the first token of a model output was generated. Only applies for runs with `run_type="llm"` and streaming enabled. |
| **session\_id**               | string           | Session identifier for the run.                                                                                               |
| **in\_dataset**               | boolean          | Indicates whether the run is included in a dataset.                                                                           |
| **parent\_run\_id**           | UUID             | Unique identifier of the parent run.                                                                                          |
| execution\_order (deprecated) | integer          | The order in which this run was executed within the trace.                                                                    |
| serialized                    | object           | Serialized state of the object executing the run if applicable.                                                               |
| manifest\_id (deprecated)     | UUID             | Identifier for a manifest associated with the span.                                                                           |
| manifest\_s3\_id              | UUID             | S3 identifier for the manifest.                                                                                               |
| inputs\_s3\_urls              | object           | S3 URLs for the inputs.                                                                                                       |
| outputs\_s3\_urls             | object           | S3 URLs for the outputs.                                                                                                      |
| price\_model\_id              | UUID             | Identifier for the pricing model applied to the run.                                                                          |
| app\_path                     | string           | Application (UI) path for this run.                                                                                           |
| last\_queued\_at              | datetime         | Last time the span was queued.                                                                                                |
| share\_token                  | string           | Token for sharing access to the run's data.                                                                                   |

Here is an example of a JSON representation of a run in the above format:

```json
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "name": "string",
  "inputs": {},
  "run_type": "llm",
  "start_time": "2024-04-29T00:49:12.090000",
  "end_time": "2024-04-29T00:49:12.459000",
  "extra": {},
  "error": "string",
  "execution_order": 1,
  "serialized": {},
  "outputs": {},
  "parent_run_id": "f8faf8c1-9778-49a4-9004-628cdb0047e5",
  "manifest_id": "82825e8e-31fc-47d5-83ce-cd926068341e",
  "manifest_s3_id": "0454f93b-7eb6-4b9d-a203-f1261e686840",
  "events": [{}],
  "tags": ["foo"],
  "inputs_s3_urls": {},
  "outputs_s3_urls": {},
  "trace_id": "df570c03-5a03-4cea-8df0-c162d05127ac",
  "dotted_order": "20240429T004912090000Z497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "status": "string",
  "child_run_ids": ["497f6eca-6276-4993-bfeb-53cbbbba6f08"],
  "direct_child_run_ids": ["497f6eca-6276-4993-bfeb-53cbbbba6f08"],
  "parent_run_ids": ["f8faf8c1-9778-49a4-9004-628cdb0047e5"],
  "feedback_stats": {
    "correctness": {
      "n": 1,
      "avg": 1.0
    }
  },
  "reference_example_id": "9fb06aaa-105f-4c87-845f-47d62ffd7ee6",
  "total_tokens": 0,
  "prompt_tokens": 0,
  "completion_tokens": 0,
  "total_cost": "string",
  "prompt_cost": "string",
  "completion_cost": "string",
  "price_model_id": "0b5d9575-bec3-4256-b43a-05893b8b8440",
  "first_token_time": null,
  "session_id": "1ffd059c-17ea-40a8-8aef-70fd0307db82",
  "app_path": "string",
  "last_queued_at": null,
  "in_dataset": true,
  "share_token": "d0430ac3-04a1-4e32-a7ea-57776ad22c1c"
}
```

#### What is `dotted_order`?

A run's dotted order is a sortable key that fully specifies its location within the tracing hierarchy.

Take the following example:

```python
import langsmith as ls

@ls.traceable
def grandchild():
    p("grandchild")

@ls.traceable
def child():
    grandchild()

@ls.traceable
def parent():
    child()
```

If you print out the IDs at each stage, you may get the following:

```python
parent	run_id=0e01bf50-474d-4536-810f-67d3ee7ea3e7	trace_id=0e01bf50-474d-4536-810f-67d3ee7ea3e7  parent_run_id=null	dotted_order=20240919T171648521691Z0e01bf50-474d-4536-810f-67d3ee7ea3e7
child	run_id=a8024e23-5b82-47fd-970e-f6a5ba3f5097	trace_id=0e01bf50-474d-4536-810f-67d3ee7ea3e7  parent_run_id=0e01bf50-474d-4536-810f-67d3ee7ea3e7	dotted_order=20240919T171648521691Z0e01bf50-474d-4536-810f-67d3ee7ea3e7.20240919T171648523407Za8024e23-5b82-47fd-970e-f6a5ba3f5097
grandchild	run_id=0ec6b845-18b9-4aa1-8f1b-6ba3f9fdefd6	trace_id=0e01bf50-474d-4536-810f-67d3ee7ea3e7  parent_run_id=a8024e23-5b82-47fd-970e-f6a5ba3f5097	dotted_order=20240919T171648521691Z0e01bf50-474d-4536-810f-67d3ee7ea3e7.20240919T171648523407Za8024e23-5b82-47fd-970e-f6a5ba3f5097.20240919T171648523563Z0ec6b845-18b9-4aa1-8f1b-6ba3f9fdefd6
```

Note a few invariants:

* The "id" is equal to the last 36 characters of the dotted order (the suffix after the final "Z"). See `0ec6b845-18b9-4aa1-8f1b-6ba3f9fdefd6` for example in the grandchild.
* The "trace\_id" is equal to the first UUID in the dotted order (i.e., `dotted_order.split('.')[0].split('Z')[1]`)
* If "parent\_run\_id" exists, it is the penultimate UUID in the dotted order. See `a8024e23-5b82-47fd-970e-f6a5ba3f5097` in the grandchild, for an example.
* If you split the dotted\_order on the dots, each segment is formatted as (`<run_start_time>Z<run_id>`)
